home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat1 / perlstyle.z / perlstyle
Text File  |  1998-10-30  |  11KB  |  331 lines
  1.  
  2.  
  3.  
  4. PPPPEEEERRRRLLLLSSSSTTTTYYYYLLLLEEEE((((1111))))                                                      PPPPEEEERRRRLLLLSSSSTTTTYYYYLLLLEEEE((((1111))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      perlstyle - Perl style guide
  10.  
  11. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  12.      Each programmer will, of course, have his or her own preferences in
  13.      regards to formatting, but there are some general guidelines that will
  14.      make your programs easier to read, understand, and maintain.
  15.  
  16.      The most important thing is to run your programs under the ----wwww flag at all
  17.      times.  You may turn it off explicitly for particular portions of code
  18.      via the $^W variable if you must.  You should also always run under use
  19.      strict or know the reason why not.  The use sigtrap and even use
  20.      diagnostics pragmas may also prove useful.
  21.  
  22.      Regarding aesthetics of code lay out, about the only thing Larry cares
  23.      strongly about is that the closing curly brace of a multi-line BLOCK
  24.      should line up with the keyword that started the construct.  Beyond that,
  25.      he has other preferences that aren't so strong:
  26.  
  27.      +o   4-column indent.
  28.  
  29.      +o   Opening curly on same line as keyword, if possible, otherwise line
  30.          up.
  31.  
  32.      +o   Space before the opening curly of a multi-line BLOCK.
  33.  
  34.      +o   One-line BLOCK may be put on one line, including curlies.
  35.  
  36.      +o   No space before the semicolon.
  37.  
  38.      +o   Semicolon omitted in "short" one-line BLOCK.
  39.  
  40.      +o   Space around most operators.
  41.  
  42.      +o   Space around a "complex" subscript (inside brackets).
  43.  
  44.      +o   Blank lines between chunks that do different things.
  45.  
  46.      +o   Uncuddled elses.
  47.  
  48.      +o   No space between function name and its opening parenthesis.
  49.  
  50.      +o   Space after each comma.
  51.  
  52.      +o   Long lines broken after an operator (except "and" and "or").
  53.  
  54.      +o   Space after last parenthesis matching on current line.
  55.  
  56.      +o   Line up corresponding items vertically.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PPPPEEEERRRRLLLLSSSSTTTTYYYYLLLLEEEE((((1111))))                                                      PPPPEEEERRRRLLLLSSSSTTTTYYYYLLLLEEEE((((1111))))
  71.  
  72.  
  73.  
  74.      +o   Omit redundant punctuation as long as clarity doesn't suffer.
  75.  
  76.      Larry has his reasons for each of these things, but he doesn't claim that
  77.      everyone else's mind works the same as his does.
  78.  
  79.      Here are some other more substantive style issues to think about:
  80.  
  81.      +o   Just because you _C_A_N do something a particular way doesn't mean that
  82.          you _S_H_O_U_L_D do it that way.  Perl is designed to give you several ways
  83.          to do anything, so consider picking the most readable one.  For
  84.          instance
  85.  
  86.              open(FOO,$foo) || die "Can't open $foo: $!";
  87.  
  88.          is better than
  89.  
  90.              die "Can't open $foo: $!" unless open(FOO,$foo);
  91.  
  92.          because the second way hides the main point of the statement in a
  93.          modifier.  On the other hand
  94.  
  95.              print "Starting analysis\n" if $verbose;
  96.  
  97.          is better than
  98.  
  99.              $verbose && print "Starting analysis\n";
  100.  
  101.          because the main point isn't whether the user typed ----vvvv or not.
  102.  
  103.          Similarly, just because an operator lets you assume default arguments
  104.          doesn't mean that you have to make use of the defaults.  The defaults
  105.          are there for lazy systems programmers writing one-shot programs.  If
  106.          you want your program to be readable, consider supplying the
  107.          argument.
  108.  
  109.          Along the same lines, just because you _C_A_N omit parentheses in many
  110.          places doesn't mean that you ought to:
  111.  
  112.              return print reverse sort num values %array;
  113.              return print(reverse(sort num (values(%array))));
  114.  
  115.          When in doubt, parenthesize.  At the very least it will let some poor
  116.          schmuck bounce on the % key in vvvviiii.
  117.  
  118.          Even if you aren't in doubt, consider the mental welfare of the
  119.          person who has to maintain the code after you, and who will probably
  120.          put parentheses in the wrong place.
  121.  
  122.      +o   Don't go through silly contortions to exit a loop at the top or the
  123.          bottom, when Perl provides the last operator so you can exit in the
  124.          middle.  Just "outdent" it a little to make it more visible:
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PPPPEEEERRRRLLLLSSSSTTTTYYYYLLLLEEEE((((1111))))                                                      PPPPEEEERRRRLLLLSSSSTTTTYYYYLLLLEEEE((((1111))))
  137.  
  138.  
  139.  
  140.              LINE:
  141.                  for (;;) {
  142.                      statements;
  143.                    last LINE if $foo;
  144.                      next LINE if /^#/;
  145.                      statements;
  146.                  }
  147.  
  148.  
  149.      +o   Don't be afraid to use loop labels--they're there to enhance
  150.          readability as well as to allow multilevel loop breaks.  See the
  151.          previous example.
  152.  
  153.      +o   Avoid using _g_r_e_p() (or _m_a_p()) or `backticks` in a void context, that
  154.          is, when you just throw away their return values.  Those functions
  155.          all have return values, so use them.  Otherwise use a _f_o_r_e_a_c_h() loop
  156.          or the _s_y_s_t_e_m() function instead.
  157.  
  158.      +o   For portability, when using features that may not be implemented on
  159.          every machine, test the construct in an eval to see if it fails.  If
  160.          you know what version or patchlevel a particular feature was
  161.          implemented, you can test $] ($PERL_VERSION in English) to see if it
  162.          will be there.  The Config module will also let you interrogate
  163.          values determined by the CCCCoooonnnnffffiiiigggguuuurrrreeee program when Perl was installed.
  164.  
  165.      +o   Choose mnemonic identifiers.  If you can't remember what mnemonic
  166.          means, you've got a problem.
  167.  
  168.      +o   While short identifiers like $gotit are probably ok, use underscores
  169.          to separate words.  It is generally easier to read
  170.          $var_names_like_this than $VarNamesLikeThis, especially for non-
  171.          native speakers of English. It's also a simple rule that works
  172.          consistently with VAR_NAMES_LIKE_THIS.
  173.  
  174.          Package names are sometimes an exception to this rule.  Perl
  175.          informally reserves lowercase module names for "pragma" modules like
  176.          integer and strict.  Other modules should begin with a capital letter
  177.          and use mixed case, but probably without underscores due to
  178.          limitations in primitive file systems' representations of module
  179.          names as files that must fit into a few sparse bytes.
  180.  
  181.      +o   You may find it helpful to use letter case to indicate the scope or
  182.          nature of a variable. For example:
  183.  
  184.              $ALL_CAPS_HERE   constants only (beware clashes with perl vars!)
  185.              $Some_Caps_Here  package-wide global/static
  186.              $no_caps_here    function scope my() or local() variables
  187.  
  188.          Function and method names seem to work best as all lowercase.  E.g.,
  189.          $obj->_a_s__s_t_r_i_n_g().
  190.  
  191.          You can use a leading underscore to indicate that a variable or
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PPPPEEEERRRRLLLLSSSSTTTTYYYYLLLLEEEE((((1111))))                                                      PPPPEEEERRRRLLLLSSSSTTTTYYYYLLLLEEEE((((1111))))
  203.  
  204.  
  205.  
  206.          function should not be used outside the package that defined it.
  207.  
  208.      +o   If you have a really hairy regular expression, use the /x modifier
  209.          and put in some whitespace to make it look a little less like line
  210.          noise.  Don't use slash as a delimiter when your regexp has slashes
  211.          or backslashes.
  212.  
  213.      +o   Use the new "and" and "or" operators to avoid having to parenthesize
  214.          list operators so much, and to reduce the incidence of punctuation
  215.          operators like && and ||.  Call your subroutines as if they were
  216.          functions or list operators to avoid excessive ampersands and
  217.          parentheses.
  218.  
  219.      +o   Use here documents instead of repeated _p_r_i_n_t() statements.
  220.  
  221.      +o   Line up corresponding things vertically, especially if it'd be too
  222.          long to fit on one line anyway.
  223.  
  224.              $IDX = $ST_MTIME;
  225.              $IDX = $ST_ATIME       if $opt_u;
  226.              $IDX = $ST_CTIME       if $opt_c;
  227.              $IDX = $ST_SIZE        if $opt_s;
  228.  
  229.              mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!";
  230.              chdir($tmpdir)      or die "can't chdir $tmpdir: $!";
  231.              mkdir 'tmp',   0777 or die "can't mkdir $tmpdir/tmp: $!";
  232.  
  233.  
  234.      +o   Always check the return codes of system calls.  Good error messages
  235.          should go to STDERR, include which program caused the problem, what
  236.          the failed system call and arguments were, and VERY IMPORTANT) should
  237.          contain the standard system error message for what went wrong.
  238.          Here's a simple but sufficient example:
  239.  
  240.              opendir(D, $dir)     or die "can't opendir $dir: $!";
  241.  
  242.  
  243.      +o   Line up your translations when it makes sense:
  244.  
  245.              tr [abc]
  246.                 [xyz];
  247.  
  248.  
  249.      +o   Think about reusability.  Why waste brainpower on a one-shot when you
  250.          might want to do something like it again?  Consider generalizing your
  251.          code.  Consider writing a module or object class.  Consider making
  252.          your code run cleanly with use strict and ----wwww in effect.  Consider
  253.          giving away your code.  Consider changing your whole world view.
  254.          Consider... oh, never mind.
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. PPPPEEEERRRRLLLLSSSSTTTTYYYYLLLLEEEE((((1111))))                                                      PPPPEEEERRRRLLLLSSSSTTTTYYYYLLLLEEEE((((1111))))
  269.  
  270.  
  271.  
  272.      +o   Be consistent.
  273.  
  274.      +o   Be nice.
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.